home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / ConfigWidg.3 < prev    next >
Text File  |  1995-07-21  |  33KB  |  834 lines
  1. '\"
  2. '\" Copyright (c) 1990-1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/ConfigWidg.3,v 1.18 93/04/30 08:51:56 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_ConfigureWidget tkc 3.3
  206. .BS
  207. .SH NAME
  208. Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_FreeOptions \- process configuration options for widgets
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tk.h>\fR
  212. .sp
  213. int
  214. \fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
  215. .sp
  216. int
  217. \fBTk_Offset(\fItype, field\fB)\fR
  218. .sp
  219. int
  220. \fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
  221. .sp
  222. .VS
  223. \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
  224. .VE
  225. .SH ARGUMENTS
  226. .AS Tk_ConfigSpec *widgRec
  227. .AP Tcl_Interp *interp in
  228. Interpreter to use for returning error messages.
  229. .AP Tk_Window tkwin in
  230. Window used to represent widget (needed to set up X resources).
  231. .AP Tk_ConfigSpec *specs in
  232. Pointer to table specifying legal configuration options for this
  233. widget.
  234. .AP int argc in
  235. Number of arguments in \fIargv\fR.
  236. .AP char **argv in
  237. Command-line options for configuring widget.
  238. .AP char *widgRec in/out
  239. Points to widget record structure.  Fields in this structure get
  240. modified by \fBTk_ConfigureWidget\fR to hold configuration information.
  241. .AP int flags in
  242. If non-zero, then it specifies an OR-ed combination of flags that
  243. control the processing of configuration information.
  244. TK_CONFIG_ARGV_ONLY causes the option database and defaults to be
  245. ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to
  246. selectively disable entries in \fIspecs\fR.
  247. .AP "type name" type in
  248. The name of the type of a widget record.
  249. .AP "field name" field in
  250. The name of a field in records of type \fItype\fR.
  251. .AP char *argvName in
  252. The name used on Tcl command lines to refer to a particular option
  253. (e.g. when creating a widget or invoking the \fBconfigure\fR widget
  254. command).  If non-NULL, then information is returned only for this
  255. option.  If NULL, then information is returned for all available
  256. options.
  257. .AP Display *display in
  258. Display containing widget whose record is being freed;  needed in
  259. order to free up resources.
  260. .BE
  261. .SH DESCRIPTION
  262. .PP
  263. \fBTk_ConfigureWidget\fR is called to configure various aspects of a
  264. widget, such as colors, fonts, border width, etc.
  265. It is intended as a convenience procedure to reduce the amount
  266. of code that must be written in individual widget managers to
  267. handle configuration information.
  268. It is typically
  269. invoked when widgets are created, and again when the \fBconfigure\fR
  270. command is invoked for a widget.
  271. Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
  272. can be used in other situations where \fIargc-argv\fR information
  273. is to be used to fill in a record structure, such as configuring
  274. graphical elements for a canvas widget or entries of a menu.
  275. .PP
  276. \fBTk_ConfigureWidget\fR processes
  277. a table specifying the configuration options that are supported
  278. (\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
  279. \fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
  280. It uses the option database and defaults specified in \fIspecs\fR
  281. to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
  282. \fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in this
  283. case it does not modify \fIinterp\fR.
  284. If an error
  285. occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will
  286. leave an error message in \fIinterp->result\fR in the standard Tcl
  287. fashion.
  288. In the event of an error return, some of the fields of \fIwidgRec\fR
  289. could already have been set, if configuration information for them
  290. was successfully processed before the error occurred.
  291. .VS
  292. The other fields will be set to reasonable initial values so that
  293. \fBTk_FreeOptions\fR can be called for cleanup.
  294. .VE
  295. .PP
  296. The \fIspecs\fR array specifies the kinds of configuration options
  297. expected by the widget.  Each of its entries specifies one configuration
  298. option and has the following structure:
  299. .DS
  300. .ta 1c 2c 3c
  301. typedef struct {
  302.     int \fItype\fR;
  303.     char *\fIargvName\fR;
  304.     char *\fIdbName\fR;
  305.     char *\fIdbClass\fR;
  306.     char *\fIdefValue\fR;
  307.     int \fIoffset\fR;
  308.     int \fIspecFlags\fR;
  309. .VS
  310.     Tk_CustomOption *\fIcustomPtr\fR;
  311. .VE
  312. } Tk_ConfigSpec;
  313. .DE
  314. .LP
  315. The \fItype\fR field indicates what type of configuration option this is
  316. (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for
  317. an integer value).  The \fItype\fR field indicates how to use the
  318. value of the option (more on this below).
  319. The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'',
  320. which is compared with the values in \fIargv\fR (if \fIargvName\fR is
  321. NULL it means this is a grouped entry;  see GROUPED ENTRIES below).  The
  322. \fIdbName\fR and \fIdbClass\fR fields are used to look up a value
  323. for this option in the option database.  The \fIdefValue\fR field
  324. specifies a default value for this configuration option if no
  325. value is specified in either \fIargv\fR or the option database.
  326. \fIOffset\fR indicates where in \fIwidgRec\fR to store information
  327. about this option, and \fIspecFlags\fR contains additional information
  328. to control the processing of this configuration option (see FLAGS
  329. below).
  330. The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
  331. TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.
  332. .PP
  333. \fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
  334. (if any) configuration options are specified there.  \fIArgv\fR
  335. must contain an even number of fields;  the first of each pair
  336. of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
  337. (unique abbreviations are acceptable),
  338. and the second field of the pair contains the value for that
  339. configuration option.  If there are entries in \fIspec\fR for which
  340. there were no matching entries in \fIargv\fR,
  341. \fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
  342. fields of the \fIspecs\fR entry to probe the option database;  if
  343. a value is found, then it is used as the value for the option.
  344. Finally, if no entry is found in the option database, the
  345. \fIdefValue\fR field of the \fIspecs\fR entry is used as the
  346. value for the configuration option.  If the \fIdefValue\fR is
  347. NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in
  348. \fIflags\fR, then there is no default value and this \fIspecs\fR entry
  349. will be ignored if no value is specified in \fIargv\fR or the
  350. option database.
  351. .PP
  352. Once a string value has been determined for a configuration option,
  353. \fBTk_ConfigureWidget\fR translates the string value into a more useful
  354. form, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integer
  355. if \fItype\fR is TK_CONFIG_INT.  This value is then stored in the
  356. record pointed to by \fIwidgRec\fR.  This record is assumed to
  357. contain information relevant to the manager of the widget;  its exact
  358. type is unknown to \fBTk_ConfigureWidget\fR.  The \fIoffset\fR field
  359. of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store
  360. the information about this configuration option.  You should use the
  361. \fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for
  362. a description of \fBTk_Offset\fR).  The location indicated by
  363. \fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target''
  364. in the descriptions below.
  365. .PP
  366. The \fItype\fR field of each entry in \fIspecs\fR determines what
  367. to do with the string value of that configuration option.  The
  368. legal values for \fItype\fR, and the corresponding actions, are:
  369. .TP
  370. \fBTK_CONFIG_ACTIVE_CURSOR\fR
  371. The value
  372. .VS
  373. must be an ASCII string identifying a cursor in a form
  374. suitable for passing to \fBTk_GetCursor\fR. 
  375. The value is converted to a \fBCursor\fR by calling
  376. \fBTk_GetCursor\fR and the result is stored in the target.
  377. In addition, the resulting cursor is made the active cursor
  378. for \fItkwin\fR by calling \fBXDefineCursor\fR.
  379. If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
  380. may be an empty string, in which case the target and \fItkwin\fR's
  381. active cursor will be set to \fBNone\fR.
  382. If the previous value of the target
  383. wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
  384. .TP
  385. \fBTK_CONFIG_ANCHOR\fR
  386. The value must be an ASCII string identifying an anchor point in one of the ways
  387. accepted by \fBTk_GetAnchor\fR.
  388. The string is converted to a \fBTk_Anchor\fR by calling
  389. \fBTk_GetAnchor\fR and the result is stored in the target.
  390. .VE
  391. .TP
  392. \fBTK_CONFIG_BITMAP\fR
  393. The value must be an ASCII string identifying a bitmap in a form
  394. suitable for passing to \fBTk_GetBitmap\fR.  The value is converted
  395. to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
  396. is stored in the target.
  397. .VS
  398. If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
  399. may be an empty string, in which case the target is set to \fBNone\fR.
  400. .VE
  401. If the previous value of the target
  402. wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
  403. .TP
  404. \fBTK_CONFIG_BOOLEAN\fR
  405. The value must be an ASCII string specifying a boolean value.  Any
  406. of the values ``true'', ``yes'', ``on'', or ``1'',
  407. or an abbreviation of one of these values, means true;
  408. any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of
  409. one of these values, means false.
  410. The target is expected to be an integer;  for true values it will
  411. be set to 1 and for false values it will be set to 0.
  412. .TP
  413. \fBTK_CONFIG_BORDER\fR
  414. The value must be an ASCII string identifying a border color in a form
  415. suitable for passing to \fBTk_Get3DBorder\fR.  The value is converted
  416. to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
  417. is stored in the target.
  418. .VS
  419. If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
  420. may be an empty string, in which case the target will be set to NULL.
  421. .VE
  422. If the previous value of the target
  423. wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
  424. .TP
  425. \fBTK_CONFIG_CAP_STYLE\fR
  426. The value must be
  427. .VS
  428. an ASCII string identifying a cap style in one of the ways
  429. accepted by \fBTk_GetCapStyle\fR.
  430. The string is converted to an integer value corresponding
  431. to the cap style by calling
  432. \fBTk_GetCapStyle\fR and the result is stored in the target.
  433. .VE
  434. .TP
  435. \fBTK_CONFIG_COLOR\fR
  436. The value must be an ASCII string identifying a color in a form
  437. suitable for passing to \fBTk_GetColor\fR.  The value is converted
  438. to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
  439. is stored in the target.
  440. .VS
  441. If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
  442. may be an empty string, in which case the target will be set to \fBNone\fR.
  443. .VE
  444. If the previous value of the target
  445. wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
  446. .TP
  447. \fBTK_CONFIG_CURSOR\fR
  448. This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
  449. that the new cursor is not made the active one for \fItkwin\fR.
  450. .TP
  451. \fBTK_CONFIG_CUSTOM\fR
  452. .VS
  453. This option allows applications to define new option types.
  454. The \fIcustomPtr\fR field of the entry points to a structure
  455. defining the new option type.
  456. See the section CUSTOM OPTION TYPES below for details.
  457. .VE
  458. .TP
  459. \fBTK_CONFIG_DOUBLE\fR
  460. The value must be an ASCII floating-point number in
  461. the format accepted by \fBstrtol\fR.  The string is converted
  462. to a \fBdouble\fR value, and the value is stored in the
  463. target.
  464. .TP
  465. \fBTK_CONFIG_END\fR
  466. Marks the end of the table.  The last entry in \fIspecs\fR
  467. must have this type;  all of its other fields are ignored and it
  468. will never match any arguments.
  469. .TP
  470. \fBTK_CONFIG_FONT\fR
  471. The value must be an ASCII string identifying a font in a form
  472. suitable for passing to \fBTk_GetFontStruct\fR.  The value is converted
  473. to an (\fBXFontStruct *\fR) by calling \fBTk_GetFontStruct\fR and the result
  474. is stored in the target.
  475. .VS
  476. If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
  477. may be an empty string, in which case the target will be set to NULL.
  478. .VE
  479. If the previous value of the target
  480. wasn't NULL, then it is freed by passing it to \fBTk_FreeFontStruct\fR.
  481. .TP
  482. \fBTK_CONFIG_INT\fR
  483. The value must be an ASCII integer string
  484. in the format accepted by \fBstrtol\fR (e.g. ``0''
  485. and ``0x'' prefixes may be used to specify octal or hexadecimal
  486. numbers, respectively).  The string is converted to an integer
  487. value and the integer is stored in the target.
  488. .TP
  489. \fBTK_CONFIG_JOIN_STYLE\fR
  490. The value must be
  491. .VS
  492. an ASCII string identifying a join style in one of the ways
  493. accepted by \fBTk_GetJoinStyle\fR.
  494. The string is converted to an integer value corresponding
  495. to the join style by calling
  496. \fBTk_GetJoinStyle\fR and the result is stored in the target.
  497. .TP
  498. \fBTK_CONFIG_JUSTIFY\fR
  499. The value must be
  500. an ASCII string identifying a justification method in one of the
  501. ways accepted by \fBTk_GetJustify\fR.
  502. The string is converted to a \fBTk_Justify\fR by calling
  503. \fBTk_GetJustify\fR and the result is stored in the target.
  504. .TP
  505. \fBTK_CONFIG_MM\fR
  506. The value must specify a screen distance in one of the forms acceptable
  507. to \fBTk_GetScreenMM\fR.
  508. The string is converted to double-precision floating-point distance
  509. in millimeters and the value is stored in the target.
  510. .TP
  511. \fBTK_CONFIG_PIXELS\fR
  512. The value must specify screen units in one of the forms acceptable
  513. to \fBTk_GetPixels\fR.
  514. The string is converted to an integer distance in pixels and the
  515. value is stored in the target.
  516. .VE
  517. .TP
  518. \fBTK_CONFIG_RELIEF\fR
  519. The value must be an ASCII string identifying a relief in a form
  520. suitable for passing to \fBTk_GetRelief\fR.  The value is converted
  521. to an integer relief value by calling \fBTk_GetRelief\fR and the result
  522. is stored in the target.
  523. .TP
  524. \fBTK_CONFIG_STRING\fR
  525. A copy
  526. .VS
  527. of the value is made by allocating memory space with
  528. \fBmalloc\fR and copying the value into the dynamically-allocated
  529. space.  A pointer to the new string is stored in the target.
  530. If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
  531. may be an empty string, in which case the target will be set to NULL.
  532. If the previous value of the target wasn't NULL, then it is
  533. freed by passing it to \fBfree\fR.
  534. .VE
  535. .TP
  536. \fBTK_CONFIG_SYNONYM\fR
  537. This \fItype\fR value identifies special entries in \fIspecs\fR that
  538. are synonyms for other entries.  If an \fIargv\fR value matches the
  539. \fIargvName\fR of a TK_CONFIG_SYNONYM entry, the entry isn't used
  540. directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
  541. for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
  542. field in the TK_CONFIG_SYNONYM entry;  this new entry is used just
  543. as if its \fIargvName\fR had matched the \fIargv\fR value.  The
  544. synonym mechanism allows multiple \fIargv\fR values to be used for
  545. a single configuration option, such as ``\-background'' and ``\-bg''.
  546. .TP
  547. \fBTK_CONFIG_UID\fR
  548. The value is translated to a \fBTk_Uid\fR
  549. (by passing it to \fBTk_GetUid\fR).  The resulting value
  550. is stored in the target.
  551. .VS
  552. If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value
  553. is an empty string then the target will be set to NULL.
  554. .TP
  555. \fBTK_CONFIG_WINDOW\fR
  556. The value must be a window path name.  It is translated to a
  557. \fBTk_Window\fR token and the token is stored in the target.
  558. .VE
  559.  
  560. .SH "GROUPED ENTRIES"
  561. .PP
  562. In some cases it is useful to generate multiple resources from
  563. a single configuration value.  For example, a color name might
  564. be used both to generate the background color for a widget (using
  565. TK_CONFIG_COLOR) and to generate a 3-D border to draw around the
  566. widget (using TK_CONFIG_BORDER).  In cases like this it is possible
  567. to specify that several consecutive entries in \fIspecs\fR are to
  568. be treated as a group.  The first entry is used to determine a value
  569. (using its \fIargvName\fR, \fIdbName\fR,
  570. \fIdbClass\fR, and \fIdefValue\fR fields).  The value will be processed
  571. several times (one for each entry in the group), generating multiple
  572. different resources and modifying multiple targets within \fIwidgRec\fR.
  573. Each of the entries after the first must have a NULL value in its
  574. \fIargvName\fR field;  this indicates that the entry is to be grouped
  575. with the entry that precedes it.  Only the \fItype\fR and \fIoffset\fR
  576. fields are used from these follow-on entries.
  577.  
  578. .SH "FLAGS"
  579. .PP
  580. The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
  581. in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
  582. to provide additional control over the processing of configuration
  583. options.  These values are used in three different ways as
  584. described below.
  585. .PP
  586. First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
  587. the TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0),
  588. then the option database and
  589. \fIdefValue\fR fields are not used.  In this case, if an entry in
  590. \fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens:
  591. the corresponding target isn't modified.  This feature is useful
  592. when the goal is to modify certain configuration options while
  593. leaving others in their current state, such as when a \fBconfigure\fR
  594. widget command is being processed.
  595. .PP
  596. Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used
  597. .VS
  598. to control the processing of that entry.  Each \fIspecFlags\fR
  599. field may consists of an OR-ed combination of the following values:
  600. .TP
  601. \fBTK_CONFIG_COLOR_ONLY\fR
  602. If this bit is set then the entry will only be considered if the
  603. display for \fItkwin\fR has more than one bit plane.  If the display
  604. is monochromatic then this \fIspecs\fR entry will be ignored.
  605. .TP
  606. \fBTK_CONFIG_MONO_ONLY\fR
  607. If this bit is set then the entry will only be considered if the
  608. display for \fItkwin\fR has exactly one bit plane.  If the display
  609. is not monochromatic then this \fIspecs\fR entry will be ignored.
  610. .TP
  611. \fBTK_CONFIG_NULL_OK\fR
  612. This bit is only relevant for some types of entries (see the
  613. descriptions of the various entry types above).
  614. If this bit is set, it indicates that an empty string value
  615. for the field is acceptable and if it occurs then the
  616. target should be set to NULL or \fBNone\fR, depending
  617. on the type of the target.
  618. This flag is typically used to allow a
  619. feature to be turned off entirely, e.g. set a cursor value to
  620. \fBNone\fR so that a window simply inherits its parent's cursor.
  621. If this bit isn't set then empty strings are processed as strings,
  622. which generally results in an error.
  623. .TP
  624. \fBTK_CONFIG_DONT_SET_DEFAULT\fR
  625. If this bit is one, it means that the \fIdefValue\fR field of the
  626. entry should only be used for returning the default value in
  627. \fBTk_ConfigureInfo\fR.
  628. In calls to \fBTk_ConfigureWidget\fR no default will be supplied
  629. for entries with this flag set;  it is assumed that the
  630. caller has already supplied a default value in the target location.
  631. This flag provides a performance optimization where it is expensive
  632. to process the default string:  the client can compute the default
  633. once, save the value, and provide it before calling
  634. \fBTk_ConfigureWidget\fR.
  635. .TP
  636. \fBTK_CONFIG_OPTION_SPECIFIED\fR
  637. This bit is set and cleared by \fBTk_ConfigureWidget\fR.  Whenever
  638. \fBTk_ConfigureWidget\fR returns, this bit will be set in all the
  639. entries where a value was specified in \fIargv\fR.
  640. It will be zero in all other entries.
  641. This bit provides a way for clients to determine which values
  642. actually changed in a call to \fBTk_ConfigureWidget\fR.
  643. .VE
  644. .PP
  645. The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically
  646. used to specify different default values for
  647. monochrome and color displays.  This is done by creating two
  648. entries in \fIspecs\fR that are identical except for their
  649. \fIdefValue\fR and \fIspecFlags\fR fields.  One entry should have
  650. the value TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the
  651. default value for monochrome displays in its \fIdefValue\fR;  the
  652. other entry entry should have the value TK_CONFIG_COLOR_ONLY in
  653. its \fIspecFlags\fR and the appropriate \fIdefValue\fR for
  654. color displays.
  655. .PP
  656. Third, it is possible to use \fIflags\fR and \fIspecFlags\fR
  657. together to selectively disable some entries.  This feature is
  658. not needed very often.  It is useful in cases where several
  659. similar kinds of widgets are implemented in one place.  It allows
  660. a single \fIspecs\fR table to be created with all the configuration
  661. options for all the widget types.  When processing a particular
  662. widget type, only entries relevant to that type will be used.  This
  663. effect is achieved by setting the high-order bits (those in positions
  664. equal to or greater than TK_CONFIG_USER_BIT) in \fIspecFlags\fR
  665. values or in \fIflags\fR.  In order for a particular entry in
  666. \fIspecs\fR to be used, its high-order bits must match exactly
  667. the high-order bits of the \fIflags\fR value passed to
  668. \fBTk_ConfigureWidget\fR.  If a \fIspecs\fR table is being used
  669. for N different widget types, then N of the high-order bits will
  670. be used.  Each \fIspecs\fR entry will have one of more of those
  671. bits set in its \fIspecFlags\fR field to indicate the widget types
  672. for which this entry is valid.  When calling \fBTk_ConfigureWidget\fR,
  673. \fIflags\fR will have a single one of these bits set to select the
  674. entries for the desired widget type.  For a working example of
  675. this feature, see the code in tkButton.c.
  676.  
  677. .SH TK_OFFSET
  678. .PP
  679. The \fBTk_Offset\fR macro is provided as a safe way of generating
  680. the \fIoffset\fR values for entries in Tk_ConfigSpec structures.
  681. It takes two arguments:  the name of a type of record, and the
  682. name of a field in that record.  It returns the byte offset of
  683. the named field in records of the given type.
  684.  
  685. .SH TK_CONFIGUREINFO
  686. .PP
  687. The \fBTk_ConfigureInfo\fR procedure may be used to obtain
  688. information about one or all of the options for a given widget.
  689. Given a token for a window (\fItkwin\fR), a table describing the
  690. configuration options for a class of widgets (\fIspecs\fR), a
  691. pointer to a widget record containing the current information for
  692. a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument,
  693. \fBTk_ConfigureInfo\fR generates a string describing all of the
  694. configuration options for the window.  The string is placed
  695. in \fIinterp->result\fR.  Under normal circumstances
  696. it returns TCL_OK;  if an error occurs then it returns TCL_ERROR
  697. and \fIinterp->result\fR contains an error message.
  698. .PP
  699. If \fIargvName\fR is NULL, then the value left in
  700. \fIinterp->result\fR by \fBTk_ConfigureInfo\fR
  701. consists of a list of one or more entries, each of which describes
  702. one configuration option (i.e. one entry in \fIspecs\fR).  Each
  703. entry in the list will contain either two or five values.  If the
  704. corresponding entry in \fIspecs\fR has type TK_CONFIG_SYNONYM, then
  705. the list will contain two values:  the \fIargvName\fR for the entry
  706. and the \fIdbName\fR (synonym name).  Otherwise the list will contain
  707. five values:  \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR,
  708. and current value.  The current value is computed from the appropriate
  709. field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR.
  710. .PP
  711. If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL,
  712. then it indicates a single option, and information is returned only
  713. for that option.  The string placed in \fIinterp->result\fR will be
  714. a list containing two or five values as described above;  this will
  715. be identical to the corresponding sublist that would have been returned
  716. if \fIargvName\fR had been NULL.
  717. .PP
  718. The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict
  719. the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR.
  720.  
  721. .SH TK_FREEOPTIONS
  722. .PP
  723. .VS
  724. The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup
  725. to release all of the resources associated with configuration options.
  726. It scans through \fIspecs\fR and for each entry corresponding to a
  727. resource that must be explicitly freed (e.g. those with
  728. type TK_CONFIG_COLOR), it frees the resource in the widget record.
  729. If the field in the widget record doesn't refer to a resource (e.g.
  730. it contains a null pointer) then no resource is freed for that
  731. entry.
  732. After freeing a resource, \fBTk_FreeOptions\fR sets the
  733. corresponding field of the widget record to null.
  734. .VE
  735.  
  736. .SH "CUSTOM OPTION TYPES"
  737. .PP
  738. .VS
  739. Applications can extend the built-in configuration types with additional
  740. configuration types by writing procedures to parse and print options
  741. of the a type and creating a structure pointing to those procedures:
  742. .DS
  743. .ta 1c 2c 3c
  744. typedef struct Tk_CustomOption {
  745.     Tk_OptionParseProc *\fIparseProc\fR;
  746.     Tk_OptionPrintProc *\fIprintProc\fR;
  747.     ClientData \fIclientData\fR;
  748. } Tk_CustomOption;
  749.  
  750. typedef int Tk_OptionParseProc(
  751.     ClientData \fIclientData\fR,
  752.     Tcl_Interp *\fIinterp\fR,
  753.     Tk_Window \fItkwin\fR,
  754.     char *\fIvalue\fR,
  755.     char *\fIwidgRec\fR,
  756.     int \fIoffset\fR);
  757.  
  758. typedef char *Tk_OptionPrintProc(
  759.     ClientData \fIclientData\fR,
  760.     Tk_Window \fItkwin\fR,
  761.     char *\fIwidgRec\fR,
  762.     int \fIoffset\fR,
  763.     Tcl_FreeProc **\fIfreeProcPtr\fR);
  764. .DE
  765. .LP
  766. The Tk_CustomOption structure contains three fields, which are pointers
  767. to the two procedures and a \fIclientData\fR value to be passed to those
  768. procedures when they are invoked.  The \fIclientData\fR value typically
  769. points to a structure containing information that is needed by the
  770. procedures when they are parsing and printing options.
  771. .LP
  772. The \fIparseProc\fR procedure is invoked by
  773. \fBTk_ConfigureWidget\fR to parse a string and store the resulting
  774. value in the widget record.
  775. The \fIclientData\fR argument is a copy of the \fIclientData\fR
  776. field in the Tk_CustomOption structure.
  777. The \fIinterp\fR argument points to a Tcl interpreter used for
  778. error reporting.  \fITkwin\fR is a copy of the \fItkwin\fR argument
  779. to \fBTk_ConfigureWidget\fR.  The \fIvalue\fR argument is a string
  780. describing the value for the option;  it could have been specified
  781. explicitly in the call to \fBTk_ConfigureWidget\fR or it could
  782. come from the option database or a default.
  783. \fIValue\fR will never be a null pointer but it may point to
  784. an empty string.
  785. \fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to
  786. \fBTk_ConfigureWidget\fR;  it points to the start of the widget
  787. record to modify.
  788. The last argument, \fIoffset\fR, gives the offset in bytes from the start
  789. of the widget record to the location where the option value is to
  790. be placed.  The procedure should translate the string to whatever
  791. form is appropriate for the option and store the value in the widget
  792. record.  It should normally return TCL_OK, but if an error occurs
  793. in translating the string to a value then it should return TCL_ERROR
  794. and store an error message in \fIinterp->result\fR.
  795. .LP
  796. The \fIprintProc\fR procedure is called
  797. by \fBTk_ConfigureInfo\fR to produce a string value describing an
  798. existing option.
  799. Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR
  800. arguments all have the same meaning as for Tk_OptionParseProc
  801. procedures.
  802. The \fIprintProc\fR procedure should examine the option whose value
  803. is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing
  804. that option, and return a pointer to the string.
  805. If the string is stored in dynamically-allocated memory, then
  806. the procedure must set \fI*freeProcPtr\fR to the address of
  807. a procedure to call to free the string's memory;  \fBTk_ConfigureInfo\fR
  808. will call this procedure when it is finished with the string.
  809. If the result string is stored in static memory then \fIprintProc\fR
  810. need not do anything with the \fIfreeProcPtr\fR argument.
  811. .LP
  812. Once \fIparseProc\fR and \fIprintProc\fR have been defined and a
  813. Tk_CustomOption structure has been created for them, options of this
  814. new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR
  815. fields are TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point
  816. to the Tk_CustomOption structure.
  817. .VE
  818.  
  819. .SH EXAMPLES
  820. .PP
  821. Although the explanation of \fBTk_ConfigureWidget\fR is fairly
  822. complicated, its actual use is pretty straightforward.
  823. The easiest way to get started is to copy the code
  824. from an existing widget.
  825. The library implementation of frames
  826. (tkFrame.c) has a simple configuration table, and the library
  827. implementation of buttons (tkButton.c) has a much more complex
  828. table that uses many of the fancy \fIspecFlags\fR mechanisms.
  829.  
  830. .SH KEYWORDS
  831. anchor, bitmap, boolean, border, cap style, color, configuration options,
  832. cursor, custom, double, font, integer, join style, justify, millimeters,
  833. pixels, relief, synonym, uid
  834.